home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / amiga.doc < prev    next >
Text File  |  1993-07-05  |  20KB  |  829 lines
  1.  
  2.     AMIGA.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/amiga/alloca.a
  7. c.lib/amiga/c.a
  8. c.lib/amiga/chkabort
  9. c.lib/amiga/_divs
  10. c.lib/amiga/_divu
  11. c.lib/amiga/exec_dcc
  12. c.lib/amiga/_ExecSeg
  13. c.lib/amiga/exit
  14. c.lib/amiga/main
  15. c.lib/amiga/onbreak
  16. c.lib/amiga/_mods
  17. c.lib/amiga/_modu
  18. c.lib/amiga/_muls
  19. c.lib/amiga/_mulu
  20. c.lib/amiga/_SearchPath
  21. c.lib/amiga/_SearchResident
  22. c.lib/amiga/stack_abort
  23. c.lib/amiga/wbmain
  24. c.lib/amiga/x.a
  25. c.lib/amiga/rega4
  26.  
  27.  
  28. amiga/alloca                        amiga/alloca
  29.  
  30.    NAME
  31.     alloca - allocate memory from the stack
  32.  
  33.    SYNOPSIS
  34.     void *ptr = alloca(long bytes);
  35.  
  36.    FUNCTION
  37.     alloca() comes from the UNIX world.  It allocates memory off the
  38.     stack for use within a procedure.  The allocated memory is
  39.     automatically freed when the subroutine returns.
  40.  
  41.     DO NOT USE ALLOCA() IF YOU CAN HELP IT.  alloca() is not easily
  42.     portable across machines.
  43.  
  44.    NOTE
  45.     When a low stack condition arises, alloca() will abort by printing
  46.     an error message and calling abort();  alloca() does NOT currently
  47.     try to allocate dynamic memory when it runs out of stack.
  48.  
  49.     Some implementations of alloca() use alloca(0) to free allocated
  50.     stack.    This feature is NOT currently implemented in DICE's
  51.     alloca() call.
  52.  
  53.    EXAMPLE
  54.     #include <alloca.h>
  55.     #include <stdio.h>
  56.  
  57.     main(ac, av)
  58.     char *av[];
  59.     {
  60.         char *ptr;
  61.         if (ac == 1) {
  62.         puts("test string");
  63.         exit(1);
  64.         }
  65.         ptr = alloca(strlen(av[1]) + 8);
  66.         sprintf(ptr, "FOO.%s", av[1]);
  67.         puts(ptr);
  68.         return(0);
  69.     }
  70.  
  71.    SEE ALSO
  72.     setjmp(), longjmp()
  73.  
  74.  
  75.  
  76. amiga/c.a                        amiga/c.a
  77.  
  78.    NAME
  79.     c.a  - DICE startup module for all C programs
  80.  
  81.    SYNOPSIS
  82.     c.a is entered when the program segment is run
  83.  
  84.    FUNCTION
  85.     DCC specifies DLIB:C.O first when linking objects into an
  86.     executable.  C.O also exists in C.LIB but is not normally pulled
  87.     since it is already included in the link line.
  88.  
  89.     C.O does the following:
  90.  
  91.         (1) save non-scratch registers
  92.  
  93.         (2) If Resident:
  94.             Allocate space for both data & bss and copy the
  95.             initialized data into the allocated space.    Clear
  96.             the BSS portion of the data space
  97.         Else
  98.             The BSS has already been allocated by the load module
  99.             but not cleared, Clear the BSS portion of the data space
  100.  
  101.         (3) Clear the ^C signal
  102.  
  103.         (4) Setup _SysBase
  104.  
  105.         (5) Call all AUTOINIT subroutines (this usually results in at
  106.         least the dos.library being openned).
  107.  
  108.         (6) call _main()    (usually in c.lib as well)
  109.  
  110.         (7) fall through to _exit(0)
  111.  
  112.     Note that while c.a falls through to _exit(0) after calling _main(),
  113.     _main itself calls main() with: exit(main(args...));  Thus, main()
  114.     is always expected to return a valid value (i.e. not void).
  115.  
  116.     C.O also handles the low level exit _exit() (__exit:) in the
  117.     following sequence:
  118.  
  119.         (1) Call autoinit exit subroutines (this normally closes the
  120.         DOS library and other automatically openned libraries such
  121.         as floating point libraries).
  122.  
  123.         (2) Free all memory allocated by the task, including the small
  124.         data segment & BSS space.  Note that all variables that we
  125.         use after this have already been placed in registers since
  126.         the dataspace is no longer valid.
  127.  
  128.         (3) If the _WBMsg is not NULL then:
  129.         (a) Forbid()
  130.         (b) ReplyMsg(_WBMsg)
  131.  
  132.         (4) restore original registers and rts (exit out of the process)
  133.  
  134.  
  135.    NOTE
  136.     Normally the programmer does not overide the startup object file
  137.     (c.o) since this is the entry point into the program.  However, in
  138.     many cases a programmer will want to overide _main().  I.E.:
  139.  
  140.     _main(len, arg)
  141.     int len;
  142.     char *arg;
  143.     {
  144.         ...
  145.     }
  146.  
  147.     In which case he is given the length and arg pointer passed to the
  148.     program on startup.  When you overide _main() you cannot call any
  149.     stdio (fopen, fclose, puts, etc...), low level IO (open, close,
  150.     read, write, etc...), or memory allocation routines.
  151.  
  152.     Normally _main will be overriden if the program makes only system
  153.     calls (such as Open, Close, Read, Write, FindTask, etc...).
  154.     Overriding the c.lib generally makes executables much smaller as no
  155.     extranious stdio/low level IO routines are brought in from c.lib .
  156.  
  157.     Normally you exit out of _main by calling _exit(code) (note the
  158.     underscore).
  159.  
  160.    SEE ALSO
  161.  
  162.  
  163. amiga/chkabort                        amiga/chkabort
  164.  
  165.    NAME
  166.     chkabort - check for ^C and take the appropriate action
  167.  
  168.    SYNOPSIS
  169.     (void) chkabort(void);
  170.  
  171.    FUNCTION
  172.     Checks for a ^C and takes the appropriate action.  If the appropriate
  173.     action is to exit than this routine does not return.  stdio and other
  174.     routines will call chkabort() at various points.
  175.  
  176.     The action taken by ^C may be set by the signal() or onbreak() calls.
  177.  
  178.    EXAMPLE
  179.     /*
  180.      *  wait for somebody to hit ^C (note that this is very wasteful of
  181.      *  CPU and thus isn't a real good example).
  182.      */
  183.  
  184.     main()
  185.     {
  186.         int i;
  187.  
  188.         for (i = 0; i < 10000000; ++i)
  189.         chkabort();
  190.         return(0);
  191.     }
  192.  
  193.    SEE ALSO
  194.     onbreak, atexit, signal
  195.  
  196.  
  197. amiga/_divs                        amiga/_divs
  198.  
  199.    NAME
  200.     _divs - signed long divide 32/32->32 assembly tag
  201.         not callable from C
  202.  
  203.    ENTRY
  204.     D0 = 32 bit signed integer
  205.     D1 = 32 bit signed integer
  206.  
  207.    RETURN
  208.     D0 = D0 / D1
  209.  
  210.    FUNCTION
  211.     This is an assembly function that DICE uses whenever it needs to
  212.     do a long division.  This function is not callable from C.
  213.  
  214.    SEE ALSO
  215.     _divu, _mods, _modu, _muls, _mulu
  216.  
  217.  
  218. amiga/_divu                        amiga/_divu
  219.  
  220.    NAME
  221.     _divu - unsigned long divide 32/32->32 assembly tag
  222.         not callable from C
  223.  
  224.    ENTRY
  225.     D0 = 32 bit unsigned integer
  226.     D1 = 32 bit unsigned integer
  227.  
  228.    RETURN
  229.     D0 = D0 / D1
  230.  
  231.    FUNCTION
  232.     This is an assembly function that DICE uses whenever it needs to do
  233.     an unsigned long division.  This function is not callable from C.
  234.  
  235.    SEE ALSO
  236.     _divs, _mods, _modu, _muls, _mulu
  237.  
  238.  
  239.  
  240. amiga/exec_dcc                        amiga/exec_dcc
  241.  
  242.    NAME
  243.     exec_dcc - call DICE executable
  244.  
  245.    FUNCTION
  246.     DO NOT EVER USE THIS FUNCTION.    This is an internal DICE function
  247.     used by DCC and is subject to change without notice.  This function
  248.     can easily break under new versions of the OS and special care is
  249.     taken by DCC when using it.
  250.  
  251.     The 2.0 version of the Amiga operating system has calls that will
  252.     properly accomplish this operation.
  253.  
  254.    SEE ALSO
  255.     _ExecSeg
  256.  
  257.  
  258. amiga/_ExecSeg                        amiga/_ExecSeg
  259.  
  260.    NAME
  261.     _ExecSeg - call a segment
  262.  
  263.    FUNCTION
  264.     DO NOT EVER USE THIS FUNCTION.    This is an internal DICE function
  265.     used by DCC and is subject to change without notice.  This function
  266.     can easily break under new versions of the OS and special care is
  267.     taken by DCC when using it.
  268.  
  269.     The 2.0 version of the Amiga operating system has calls that will
  270.     properly accomplish this operation.
  271.  
  272.    SEE ALSO
  273.     exec_dcc
  274.  
  275.  
  276. amiga/exit                        amiga/exit
  277.  
  278.    NAME
  279.     exit - exit from a program 'nicely'
  280.  
  281.    SYNOPSIS
  282.     (void) exit(code)
  283.  
  284.    FUNCTION
  285.     exits the program and returns the specified exit code.    Normally you
  286.     pass 0 to indicate no errors, a positive number to indicate a program
  287.     error to the parent.
  288.  
  289.     exit() closes all stdio file pointers, low level file descriptors,
  290.     perhaps other things, then finally calls _exit with the code.
  291.  
  292.     If you use main() you should call exit() to exit the program or
  293.     return an error code from main.  If you use the _main() entry
  294.     point (only for programmers dead set on optimizing executable
  295.     size and using only system library calls) you should use the _exit()
  296.     exit point.
  297.  
  298.    EXAMPLE
  299.     main(ac, av)
  300.     char *av[];
  301.     {
  302.         if (ac <= 1) {
  303.         puts("I expected an argument you idiot!");
  304.         exit(1);
  305.         }
  306.         puts("thanks for the argument!");
  307.         exit(0);
  308.     }
  309.  
  310.    SEE ALSO
  311.     main, _main, _exit
  312.  
  313.  
  314. amiga/_exit                         amiga/_exit
  315.  
  316.    NAME
  317.     _exit - exit from a program without bother to release resources
  318.  
  319.    SYNOPSIS
  320.     (void) _exit(code)
  321.     int code;
  322.  
  323.    FUNCTION
  324.     exits the program and returns the specified exit code.    Normally you
  325.     pass 0 to indicate no errors, a positive number to indicate a program
  326.     error to the parent.  Note that since auto-init openned libraries
  327.     are closed in the startup module (c.o), automatically openned
  328.     libraries WILL be automatically closed for you.  However, any
  329.     libraries you manually declare the library base variable for and
  330.     manually open must be closed by you.
  331.  
  332.     You should only call _exit() if you used the _main() entry point
  333.     (instead of the usual main()), and then only after releasing all
  334.     resources (such as file handles openned with Open()).
  335.  
  336.    EXAMPLE
  337.     /*
  338.      *  This program comes to approximately a 552 byte executable
  339.      */
  340.  
  341.     _main()
  342.     {
  343.         Write(Output(), "OW!\n", 4);
  344.         _exit(1);
  345.     }
  346.  
  347.    SEE ALSO
  348.     main, _main, exit
  349.  
  350.  
  351. amiga/main                         amiga/main
  352.  
  353.    NAME
  354.     main - main program entry
  355.  
  356.    SYNOPSIS
  357.     int
  358.     main(int argc, char **argv)
  359.     {
  360.         /* your main routine goes here */
  361.     }
  362.  
  363.    FUNCTION
  364.     The main() routine is the entry point called after normal
  365.     initialization of c.lib and the program enviroment is done
  366.     by the startup module (c.o) and _main() routine (in c.lib).
  367.  
  368.     under ANSI C main() is expected to return an integer exit code.
  369.     You can no longer simply fall through without returning any
  370.     value.    returning an exit code from your main routine is exactly
  371.     the same as exit()ing with it.
  372.  
  373.    NOTE
  374.     Any program run from the WORKBENCH uses a different access point.
  375.     Specifically, a program run from the workbench will run wbmain()
  376.     instead of main().  Please refer to the manual page for wbmain()
  377.     for workbench operation.
  378.  
  379.     If you do not supply a wbmain() a dummy wbmain() will be supplied
  380.     by the library which simply exits out of the program.
  381.  
  382.    EXAMPLE
  383.     #include <stdio.h>
  384.  
  385.     int
  386.     main(ac, av)
  387.     int ac;
  388.     char **av;
  389.     {
  390.         int i;
  391.         for (i = 0; i < ac; ++i) {
  392.         printf("Arg #%d = %s\n", i, av[i]);
  393.         }
  394.         return(0);
  395.     }
  396.  
  397.     1> sampleprogram this is a test
  398.     Arg #0 = sampleprogram
  399.     Arg #1 = this
  400.     Arg #2 = is
  401.     Arg #3 = a
  402.     Arg #4 = test
  403.     1>
  404.  
  405.    SEE ALSO
  406.     wbmain, _main, exit, _exit
  407.  
  408.  
  409. amiga/onbreak                         amiga/onbreak
  410.  
  411.    NAME
  412.     onbreak - set special ^C handler    (not ANSI)
  413.  
  414.    SYNOPSIS
  415.     typedef int (*fptr)();
  416.  
  417.     fptr oldfunc = onbreak(newfunc);
  418.     fptr newfunc;
  419.  
  420.    FUNCTION
  421.     onbreak() sets a special function to handle ^C.  It takes a pointer to
  422.     this function and returns a pointer to the previous onbreak function,
  423.     if any.  When ^C is hit, the special onbreak function is called before
  424.     any other action.
  425.  
  426.     If the onbreak function returns a non-zero value, ^C aborts the program
  427.     like it usually does.  If the function returns 0, however, the ^C
  428.     is completely ignored.
  429.  
  430.    EXAMPLE
  431.     /*
  432.      *  note: The reentrancy check is needed because of both the puts
  433.      *      and the sleep() all.
  434.      */
  435.  
  436.     #include <stdio.h>
  437.     #include <stdlib.h>
  438.  
  439.     int
  440.     brk()
  441.     {
  442.         static short cnt = 0;   /*    check for reentrancy */
  443.  
  444.         if (cnt)                /*  if not 0 then reentered!    */
  445.         return(0);
  446.         ++cnt;
  447.  
  448.         puts("Nah Nah, you can't break me!");
  449.         sleep(1);
  450.         --cnt;
  451.         return(0);
  452.     }
  453.  
  454.     int
  455.     main()
  456.     {
  457.         short i;
  458.  
  459.         onbreak(brk);
  460.         puts("Hit ^C while I loop from 1 to 100, as many times as you want");
  461.         sleep(2);
  462.         for (i = 1; i <= 100; ++i)
  463.         printf("Loop, counting, count = %d\n", i);
  464.         return(0);
  465.     }
  466.  
  467.    SEE ALSO
  468.     atexit
  469.  
  470.  
  471. amiga/_main                         amiga/_main
  472.  
  473.    NAME
  474.     _main - main program entry, bypass standard c.lib initialization
  475.  
  476.    SYNOPSIS
  477.     void _main(int arglen, char *argptr)
  478.     {
  479.         /* your main routine goes here */
  480.     }
  481.  
  482.    FUNCTION
  483.     The _main() entry point is called by the startup module (c.o).
  484.     Normally _main() is part of c.lib and does stdio and other
  485.     initialization before calling the user main() routine.  _main()
  486.     is responsible for openning the stderr channel as well.
  487.  
  488.     However, if you specify your own _main() you will overide the
  489.     c.lib version.    Normally you either fall through or _exit() from
  490.     _main.
  491.  
  492.     A programmable can use the _main entry point when the executable
  493.     uses nothing but system library routines.  That is, you make no
  494.     calls to stdio functions such as puts(), printf(), etc..., to low
  495.     level IO routines such as open(), close(), read(), etc..., or
  496.     malloc() or any routine that uses malloc().
  497.  
  498.     Self contained routines such as strcpy() may still be called, and, of
  499.     course, you may open any libraries you wish and make library calls.
  500.  
  501.     Since the auto-library openning and closing is done by the startup
  502.     module (c.o), "dos.library" will still be openned for you
  503.     automatically if you make any DOS calls.
  504.  
  505.     Using the _main entry point usually results in a substantially
  506.     smaller executable because stdio and other library routines
  507.     referenced by the c.lib _main() and exit() are never referenced
  508.     and thus never become part of the executable.  It is NOT SUGGESTED
  509.     that beginning C programmers use the _main() entry point.
  510.  
  511.    NOTE
  512.     _main is called by the startup module whether the program was run
  513.     from the CLI or the WORKBENCH.    You must detect which yourself and
  514.     also deal with the workbench message yourself.
  515.  
  516.    EXAMPLE
  517.     /*
  518.      *  This program comes to approximately a 552 byte executable
  519.      */
  520.  
  521.     _main()
  522.     {
  523.         Write(Output(), "UG!\n", 4);
  524.         _exit(1);
  525.     }
  526.  
  527.    SEE ALSO
  528.     _exit, main, exit
  529.  
  530.  
  531. amiga/_mods                        amiga/_mods
  532.  
  533.    NAME
  534.     _mods - signed long modulus 32%32->32 assembly tag
  535.         not callable from C
  536.  
  537.    ENTRY
  538.     D0 = 32 bit signed integer
  539.     D1 = 32 bit signed integer
  540.  
  541.    RETURN
  542.     D0 = D0 % D1
  543.  
  544.    FUNCTION
  545.     This is an assembly function that DICE uses whenever it needs to
  546.     do a long modulus.  This function is not callable from C.
  547.  
  548.    SEE ALSO
  549.     _divs, _divu, _modu, _muls, _mulu
  550.  
  551.  
  552. amiga/_modu                        amiga/_modu
  553.  
  554.    NAME
  555.     _modu - unsigned long modulus 32%32->32 assembly tag
  556.         not callable from C
  557.  
  558.    ENTRY
  559.     D0 = 32 bit unsigned integer
  560.     D1 = 32 bit unsigned integer
  561.  
  562.    RETURN
  563.     D0 = D0 % D1
  564.  
  565.    FUNCTION
  566.     This is an assembly function that DICE uses whenever it needs to do
  567.     an unsigned long modulus.  This function is not callable from C.
  568.  
  569.    SEE ALSO
  570.     _divs, _divu, _mods, _muls, _mulu
  571.  
  572.  
  573. amiga/_muls                        amiga/_muls
  574.  
  575.    NAME
  576.     _muls - signed long multiply 32*32->32 assembly tag
  577.         not callable from C
  578.  
  579.    ENTRY
  580.     D0 = 32 bit signed integer
  581.     D1 = 32 bit signed integer
  582.  
  583.    RETURN
  584.     D0 = D0 * D1
  585.  
  586.    FUNCTION
  587.     This is an assembly function that DICE uses whenever it needs to
  588.     do a long multiply.  This function is not callable from C.
  589.  
  590.    SEE ALSO
  591.     _divs, _divu, _mods, _modu, _mulu
  592.  
  593.  
  594. amiga/_mulu                        amiga/_mulu
  595.  
  596.    NAME
  597.     _mulu - unsigned long multiply 32/32->32 assembly tag
  598.         not callable from C
  599.  
  600.    ENTRY
  601.     D0 = 32 bit unsigned integer
  602.     D1 = 32 bit unsigned integer
  603.  
  604.    RETURN
  605.     D0 = D0 * D1
  606.  
  607.    FUNCTION
  608.     This is an assembly function that DICE uses whenever it needs to do
  609.     an unsigned long multiply.  This function is not callable from C.
  610.  
  611.    SEE ALSO
  612.     _divs, _divu, _mods, _modu, _muls
  613.  
  614.  
  615. amiga/_SearchPath                    amiga/_SearchPath
  616.  
  617.    NAME
  618.     _SearchPath - search the current Path for an executable file
  619.  
  620.    FUNCTION
  621.     DO NOT EVER USE THIS FUNCTION.    This is an internal DICE function
  622.     used by DCC and is subject to change without notice.  This function
  623.     can easily break under new versions of the OS and special care is
  624.     taken by DCC when using it.
  625.  
  626.     The 2.0 version of the Amiga operating system has calls that will
  627.     properly accomplish this operation.
  628.  
  629.    SEE ALSO
  630.     _SearchResident
  631.  
  632.  
  633. amiga/_SearchResident                    amiga/_SearchResident
  634.  
  635.    NAME
  636.     _SearchResident - search the Resident list for an executable
  637.  
  638.    FUNCTION
  639.     DO NOT EVER EVER EVER USE THIS FUNCTION.  This is an internal DICE
  640.     function used by DCC and is subject to change without notice.  This
  641.     function can easily break under new versions of the OS and special
  642.     care is taken by DCC when using it.
  643.  
  644.     The 2.0 version of the Amiga operating system has calls that will
  645.     properly accomplish this operation.
  646.  
  647.    SEE ALSO
  648.     _SearchPath
  649.  
  650.  
  651. amiga/stack_abort                      amiga/stack_abort
  652.  
  653.    NAME
  654.     stack_abort - exit point when dynamic stack allocation fails
  655.  
  656.    SYNOPSIS
  657.  
  658.     void
  659.     stack_abort(void)
  660.     {
  661.         /* .. your exit code .. */
  662.         abort();
  663.     }
  664.  
  665.    FUNCTION
  666.     When dynamic stack allocation is enabled via the -gs option and
  667.     such an allocation fails, stack_abort() is called.  If you do
  668.     not specify a stack_abort() routine, the c.lib stack_abort()
  669.     will be used and simply call abort().
  670.  
  671.     If you do specify a stack_abort() routine, you have two choices.
  672.     (1) You can exit out of the program, or (2) you can simply return
  673.     from the subroutine which RETRIES the allocation, and calls
  674.     stack_abort() again if it fails.
  675.  
  676.     The program has about 2KB of stack left at the time this function
  677.     is called.
  678.  
  679.     Since a low memory condition exists when this function is called
  680.     you should NOT do anything that might require additional
  681.     allocations!
  682.  
  683.    EXAMPLE
  684.     none - anybody got a good example?
  685.  
  686.    SEE ALSO
  687.     abort, exit
  688.  
  689.  
  690.  
  691. amiga/x.a                         amiga/x.a
  692.  
  693.    NAME
  694.     x.a - autoinit terminating tags
  695.  
  696.    SYNOPSIS
  697.  
  698.    FUNCTION
  699.     The x.o module is the last object module in the link line DCC
  700.     specifies to DLINK when linking an executable.    This module
  701.     terminates the autoinit and autoexit sections with an RTS allowing
  702.     the base of the section(s) to be called by the startup and exit
  703.     code.
  704.  
  705.     autoinit/exit sections work as follows: Any object module may
  706.     define a specially named section which will be linked, in sequence,
  707.     with other module's sections of the same name.  These sections
  708.     contain only code and NO RTS.  The terminating module X.O adds a
  709.     single RTS to each section allowing the base of the section to be
  710.     called by the startup/exit module (C.O), propogating through all
  711.     autoinit/exit routines before hitting the RTS placed in the section
  712.     by X.O
  713.  
  714.     DICE uses autoinit/exit sections to handle the following things:
  715.  
  716.     (1)     Code to initialize initialized data containing references to
  717.         other initialized data (i.e.  int a, *b = &a;)  when the code
  718.         must be made residentable.  This precludes the need for the
  719.         startup code to handle Data-Data Reloc32's for resident code.
  720.  
  721.     (2)     Code to open libraries whos base variables are referenced but
  722.         never declared.  _DOSBase and the various floating point
  723.         libraries are automatically openned in this way whenever
  724.         library calls to them are made.
  725.  
  726.         This precludes the need for DICE to have complex, room-
  727.         consuming, and many times unncessary code in c.lib to
  728.         handle these situations.
  729.  
  730.     (3)     Code to close libraries that were openned by (2) on exit.
  731.  
  732.     (4)     Entry points for the special __autoinit keyword (registered
  733.         versions of DICE only).
  734.  
  735.  
  736.    SEE ALSO
  737.     c.a
  738.  
  739.  
  740. amiga/wbmain                         amiga/wbmain
  741.  
  742.    NAME
  743.     wbmain - main program entry when run from workbench
  744.  
  745.    SYNOPSIS
  746.  
  747.     int
  748.     wbmain(struct WBStartup *wbs)
  749.     {
  750.         /*    your main code goes here */
  751.         return(exitcode);
  752.     }
  753.  
  754.    FUNCTION
  755.     The wbmain() routine is the entry point called after normal
  756.     initialization of c.lib and the program enviroment is done
  757.     by the startup module (c.o) and _main() routine (in c.lib).
  758.  
  759.     wbmain() is called when the program is run from the workbench,
  760.     main() is called when the program is run from the CLI.  Currently
  761.     the exit code is ignored.
  762.  
  763.     The standard workbench startup message is passed to wbmain(), you
  764.     can process or ignore this message as you like but should NOT
  765.     ReplyMsg() it.  I repeat, do NOT ReplyMsg() it.  When you return
  766.     from wbmain() or exit() out of the program the exit code will
  767.     automatically deal with the message.
  768.  
  769.    EXAMPLE
  770.     /*
  771.      *  If run from the workbench this program will create a file
  772.      *  T:XX instead of printing something on the console (since there
  773.      *  is no console in that case).
  774.      */
  775.  
  776.     #include <stdio.h>
  777.  
  778.     int
  779.     main(ac, av)
  780.     int ac;
  781.     char **av;
  782.     {
  783.         puts("This was run from a CLI");
  784.         return(0);
  785.     }
  786.  
  787.     int
  788.     wbmain(msg)
  789.     void *msg;    /*  to make the example less complex */
  790.     {
  791.         FILE *fi = fopen("T:xx", "w");
  792.         fprintf(fi, "This was run from the WORKBENCH\n");
  793.         fclose(fi);
  794.     }
  795.  
  796.    SEE ALSO
  797.     main
  798.  
  799.  
  800.  
  801. amiga/rega4                         amiga/rega4
  802.  
  803.    NAME
  804.     rega4 - return current contents of register A4
  805.  
  806.    SYNOPSIS
  807.  
  808.     char *basePtr = rega4();
  809.  
  810.    FUNCTION
  811.     rega4() is NOT geta4() .. rega4() simply returns the current
  812.     contents of the A4 register when you need it.  Note that DICE
  813.     offsets the A4 register 32766 from the actuall small-data base
  814.     so as to be able to use the entire -32768 to 32767 range to
  815.     access 64KBytes of small-data
  816.  
  817.     see also the __geta4 keyword in EXTENSIONS.DOC .. note that a
  818.     rega4() call inside a subroutine qualified with __geta4 is
  819.     guarenteed to return the data base pointer.  Also, a rega4() call
  820.     from any subroutine not called from an interrupt or a callback will
  821.     return the proper data base pointer.
  822.  
  823.  
  824.    EXAMPLE
  825.  
  826.    SEE ALSO
  827.  
  828.  
  829.